/**
 * Copyright (c) 2008-2012 Foxit  Corporation.
 * All Right Reserved.
 *  
 * The following code is copyrighted and contains proprietary information and trade secrets of Foxit Corporation. 
 * You can only redistribute files listed below to customers of your application, under a written SDK license agreement with Foxit. 
 * You cannot distribute any part of the SDK to general public, even with a SDK license agreement. 
 * Without SDK license agreement, you cannot redistribute anything.
 *
 * @file	fgsepub.h
 * @brief	Header file for EPUB ePub Module.
 * @details	This module offers:<br>
 *			1. Basic methods for doing some operation on ePub documents and package, such as loading, closing ePub documents and creating, releasing, loading, unload package.<br>
 *			2. Methods for security management of ePub documents.<br>
 *			3. Methods for getting information of ePub documents.<br>
 *			4. Methods for verifying encryption information of package.<br>
 *			5. Methods for CSS Style Settings.<br>
 *			6. Methods for getting useful information of Hyper links.<br>
 *			7. Methods for extracting image Information.<br>
 *
 * @note	If you want to purchase Foxit PDF SDK license and use ANY of the following functions, please
 *			request for enabling Base DRM module explicitly. 
 */

/**
 * @addtogroup FGSEPUB EPUB ePub
 * @brief Definitions and Methods in this module are included in fgsepub.h.
 */
/**@{*/

#ifndef __FGSEPUB__
#define __FGSEPUB__

#include "fgsepubbase.h"

#if defined(__cplusplus)
extern "C" {
#endif

/**
 * @brief                       Get the ePub module.
 *
 * @details                     Application must call this function to get the epub module first.<br>
 *
 * @return                      Reference to the ePub module.
 */
FGSDPModuleRef FGSEPUBModuleGet();

/**
 * @brief                       Stop using ePub module and release all resources.
 *
 * @details                     All loaded documents and pages will become invalid after this call.<br>
 *
 * @param[in] module            Reference to the ePub module.
 */
void FGSEPUBModuleExit(FGSDPModuleRef module);

/**
 * @brief                       Create a security object from a security handler provided.
 *
 * @param[in] securityHandler   Pointer to a <b>::SecurityHandler</b> struct provided by application.
 *
 * @return                      Return a security reference if success, else NULL.
 */
FGSEPUBSecurityRef FGSEPUBSecurityCreate(FGSEPUBSecurityHander *securityHandler);

/**
 * @brief                       Create a standard security object.
 *
 * @return                      Return a security reference if success, else NULL.
 */
FGSEPUBSecurityRef FGSEPUBSecurityCreateStd();

/**
 * @brief                       Release the security object used.
 *
 * @param[in] security          Reference to a security.
 *
 * @return                      ::kFGSErrorSuccess means success.<br>
 *                              For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSEPUBSecurityRelease(FGSEPUBSecurityRef security);

/**
 * @brief                       Create a standard package object.
 *
 * @return                      Return a pagekage reference if success, else NULL.
 */
FGSEPUBPackageRef FGSEPUBPackageCreateStd();

/**
 * @brief                       Create a package reference from a package provided.
 *
 * @details                     The package is be implemented by the user.
 *
 * @param[in] packageHandler    Pointer to a <b>::FGSEPUBPackageHandler</b> struct provided by application.
 *
 * @return                      Return a pagekage reference if success, else NULL.
 */
FGSEPUBPackageRef FGSEPUBPackageCreate(FGSEPUBPackageHandler *packageHandler);

/**
 * @brief                       Release the package used.
 *
 * @param[in] package           Reference to a package.	
 *
 * @return                      ::kFGSErrorSuccess means success.<br>
 *                              For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSEPUBPackageRelease(FGSEPUBPackageRef package);

/**
 * @brief                       Load an ePub file from stream object.
 *
 * @param[in] package           Reference to a package.
 * @param[in] ePubFile          Reference to a ePub file stream object.
 *
 * @return                      ::kFGSErrorSuccess means success.
 *                              For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSEPUBPackageLoadEpub(FGSEPUBPackageRef package, FGSFileStreamInRef ePubFile);

/** 
 * @brief                       Load an ePub file from file.
 *
 * @param[in] package           Reference to a package.
 * @param[in] file              Path of the epub file.
 *
 * @return						::kFGSErrorSuccess means success.
 *								For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSEPUBPackageLoadEpubWithFileName(FGSEPUBPackageRef package, CFStringRef file);

/**
 * @brief                       Unload the ePub file used.
 *
 * @param[in] package           Reference to a package.
 *
 * @return						::kFGSErrorSuccess means success.
 *								For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSEPUBPackageUnloadEpub(FGSEPUBPackageRef package);

/**
 * @brief                       Get encryption status when using standard security.
 *
 * @param[in] package           Reference to a package.
 *
 * @return                      The type of encryption status. Its value can be:
 *								<ul>
 *								<li>0: unencrypted.</li>
 *								<li>-1: unknown or error.</li>
 *								<li>1: standard password.</li>
 *								</ul>
 */
FGSEPUBEncryptStatus FGSEPUBPackageGetEncryptionStatus(FGSEPUBPackageRef package);

/**
 * @brief                       Check password when using standard security.
 *
 * @details                     Refer to check password in package
 *
 * @param[in] package           Reference to a package.
 * @param[in] password          The password data to check.
 *
 * @return                      True means success.
 */
Boolean FGSEPUBPackageCheckPassword(FGSEPUBPackageRef package, CFDataRef password);

/**
 * @brief                       Set password when using standard security.
 *
 * @param[in] package           Reference to a package.
 * @param[in] password          The password data to set.
 *
 * @return						::kFGSErrorSuccess means success.
 *								For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSEPUBPackageSetPassword(FGSEPUBPackageRef package, CFDataRef password);

/**
 * @brief                       Set cipher when using standard security.
 *
 * @param[in] cipher            Cipher flag, refers to enum of <b>FGSCipherFlag</b>.
 *
 * @return						::kFGSErrorSuccess means success.
 *								For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSEPUBPackageSetCipher(FGSEPUBPackageRef package, FGSCipherFlag cipher);

/**
 * @brief                       Set security when using standard security.
 *
 * @param[in] package           Reference to a standard package.
 * @param[in] security          Reference to a security to be set.
 *
 * @return                      ::kFGSErrorSuccess means success.<br>
 *                              For more definitions please see definitions <b>FGSErrorRet</b>. 
 */
FGSErrorRet FGSEPUBPackageSetSecurityHandle(FGSEPUBPackageRef package, FGSEPUBSecurityRef security);

/**
 * @brief                       Get the encrypt info.
 *
 * @param[in] package           Reference to a standard package.
 * @param[in] info              Info, refers to enum of <b>FGSEPUBEncryptInfo</b>.
 *
 * @return                      The encryption string.
 */
CFStringRef FGSEPUBPackageCopyEncryptionString(FGSEPUBPackageRef package, FGSEPUBEncryptInfo info);

/**
 * @brief                       Verify encryption.
 *
 * @param[in] package           Reference to a standard package.
 *
 * @return                      True means success.
 */
Boolean FGSEPUBPackageVerifyEncryption(FGSEPUBPackageRef package);

/**
 * @brief                       Start loading a ePub document.
 *
 * @details                     Doc loading is a progressive process. <br>
 *
 * @param[in] package			Reference to a standard package.
 * @param[out] document			Pointer to a <b>::FGSDPDocumentRef</b> object that receives the document.
 *
 * @return						::kFGSErrorToBecontinued means need continue loading.<br>
 *								For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSEPUBDocStartLoading(FGSEPUBPackageRef package, FGSDPDocumentRef *document);

/**
 * @brief                       Continue loading a ePub document.
 *
 * @details                     If "pause" parameter in provided, this function may return<br>
 *                              ::kFGSErrorToBecontinued any time during the document loading.
 *
 * @param[in] document			Reference to a document returned by ::FGSEPUBDocStartLoading function.
 * @param[in] pause				A callback mechanism allowing the document loading process<br>
 *								to be paused before it's finished. This can be NULL if you<br>
 *								don't want to pause.
 *
 * @return						::kFGSErrorSuccess means success.<br>
 *								For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSEPUBDocContinueLoading(FGSDPDocumentRef document, FGSPause *pause);

/**
 * @brief                       Set the layout param in the document loading process.
 *
 * @details                     You can only call it when change the params, but not reloading the package.
 *
 * @param[in] document			Reference to a document returned by ::FGSEPUBDocStartLoading function.
 * @param[in] font				Reference to a font object.
 * @param[in] fontSize			The font size.
 * @param[in] pageWidth			The desired page width, in page coordination.
 * @param[in] pageHeight		The desired page height, in page coordination.
 * @param[in] parseMode			Parse mode, refers to enum of <b>FGSDPParseMode</b>.
 * @param[in] writingMode		Flag for layout direction, It must be ::kFGSDPModeLRTB or ::kFGSDPModeTBRL or ::kFGSDPModeTBLR.
 *
 * @return						::kFGSErrorSuccess means success.<br>
 *								For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSEPUBDocSetLayoutParams(FGSDPDocumentRef document, FGSFontRef font, Float32 fontSize,
                                              Float32 pageWidth, Float32 pageHeight, FGSDPParseMode parseMode,
                                              FGSDPMode writingMode);
/**
 * @brief                       Close a ePub document and free all associated resources.
 *
 * @param[in] document			Reference to a document.
 *
 * @return                      ::kFGSErrorSuccess means success.<br>
 *                              For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSEPUBDocClose(FGSDPDocumentRef document);

/**
 * @brief                       Get an estimated document loading progress in percentage.
 *
 * @param[in] document			Reference to a document.
 *
 * @return                      An integer between 0 and 100 (inclusive) indicating the loading progress.
 */
SInt32 FGSEPUBDocGetLoadingProgress(FGSDPDocumentRef document);

/**
 * @brief                       Get information string about the document, like creator, modification date, etc.
 *
 * @details                     The string is output in Unicode, using UTF-16LE format. It's terminated by<br>
 *                              two consecutive zero bytes.<br>
 *
 * @param[in] document			Reference to a document.
 * @param[in] key				A byte string for the information key. Currently can be one of the followings:
 *								"Title", "Creator", "Subject", "Description", "Publisher", "Contributor", "Date",
 *								"Type", "Format", "Identifier", "Source", "Language", "Relation", "Coverage", "Rights".
 *
 * @return                      A string, user should release by calling <b>CFRelease</b>.
 */
CFStringRef FGSEPUBDocCopyInfoString(FGSDPDocumentRef document, CFStringRef key);

/**
 * @brief                       Set CSS style string into lib.
 *
 * @details                     In order to take effect the CSS style in current ePub document, User must call<br>
 *                              this function before they call ::FGSEPUBDocContinueLoading function.
 *
 * @param[in] document			Reference to a document.
 * @param[in] userStyles        CSS style string. The string is input in Unicode, using UTF-16LE format.
 *
 * @return                      ::kFGSErrorSuccess means success.<br>
 *                              For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSEPUBCSSSetUserStyles(FGSDPDocumentRef document, CFStringRef userStyles);

/**
 * @brief                       Set CSS style string for Agent.
 *
 * @details                     In order to take effect the CSS style in current ePub document, User must call<br>
 *                              this function before they call ::FGSEPUBDocContinueLoading function.
 *
 * @param[in] document			Reference to a document.
 * @param[in] agentStyles       CSS style string. The string is input in Unicode, using UTF-16LE format.
 *
 * @return                      ::kFGSErrorSuccess means success.<br>
 *                              For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSEPUBCSSSetAgentStyles(FGSDPDocumentRef document, CFStringRef agentStyles);

/**
 * @brief                       Set CSS style sheet priority order.
 *
 * @details                     In order to take effect the CSS style in current ePub document, User must call<br>
 *                              this function before they call ::FGSEPUBDocContinueLoading function.
 *
 * @param[in] document			Reference to a document.
 * @param[in] highPriority		Which belong to high priority, Refers to enum definitions of <b>FGSEPUBCSSStyle</b>.
 * @param[in] midPriority		Which belong to middle priority, Refers to enum definitions of <b>FGSEPUBCSSStyle</b>.
 * @param[in] lowPriority		Which belong to low priority, Refers to enum definitions of <b>FGSEPUBCSSStyle</b>.
 *
 * @Comments                    The three parameters must not be same.
 *
 * @return                      ::kFGSErrorSuccess means success.<br>
 *                              For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSEPUBCSSSetStyleSheetPriority(FGSDPDocumentRef document, FGSEPUBCSSStyle highPriority, FGSEPUBCSSStyle midPriority, FGSEPUBCSSStyle lowPriority);

/**
 * @brief                       Apply the CSS style set.
 *
 * @param[in] document			Reference to a document.
 *
 * @return                      ::kFGSErrorSuccess means success.<br>
 *                              For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSEPUBCSSApply(FGSDPDocumentRef document);

/**
 * @brief                       Get count of hyper links inside a page.
 *
 * @details                     This function must be called before any other link related function can
 *                              be called for the page.
 *
 * @param[in] page              Reference to a page.
 *
 * @return                      The count of links.
 */
UInt32 FGSEPUBLinkGetCount(FGSDPPageRef page);

/**
 * @brief                       Get action(s) associated with a particular hyper link.
 *
 * @param[in] page              Reference to a page.
 * @param[in] link_index        Zero-based index for the link.
 *
 * @return                      Reference to an action.
 */
FGSDPActionRef FGSEPUBLinkGetAction(FGSDPPageRef page, UInt32 linkIndex);

/**
 * @brief                       Get count of area (quadrilaterals) for a link.
 *
 * @param[in] page              Reference to a page.
 * @param[in] link_index        Zero-based index for the link.
 *
 * @return                      The count of quadrilaterals.
 */
UInt32 FGSEPUBLinkGetAreaCount(FGSDPPageRef page, UInt32 linkIndex);

/**
 * @brief                       Get a particular quadrilateral for a link.
 *
 * @param[in] page              Reference to a page.
 * @param[in] linkIndex         Zero-based index for the link.
 * @param[in] areaIndex         Zero-based index for the quadrilateral.
 *
 * @return                      An rectangle, in hundredth of points.
 */
CGRect FGSEPUBLinkGetArea(FGSDPPageRef page, UInt32 linkIndex, UInt32 areaIndex);

/**
 * @brief                       Get count of images in given page.
 *
 * @param[in] page              Reference to a page.
 *
 * @return                      The count of images.
 */
UInt32 FGSEPUBImageGetCount(FGSDPPageRef page);

/**
 * @brief                       Get rect of specific image.
 *
 * @param[in] page              Reference to a page.
 * @param[in] imageIndex        The index of the specific image.
 *
 * @return                      The rect of the specific iamge..
 */
CGRect FGSEPUBImageGetRect(FGSDPPageRef page, UInt32 imageIndex);

/**
 * @brief                       Extract an image from dest page by index.
 *
 * @param[in] page              Reference to a page.
 * @param[in] size              The size of image.
 * @param[in] imageIndex        The index of the specific image.			
 *
 * @return                      The Image extract form the page, user should release by calling CFRelease.
 */
CGImageRef FGSEPUBImageExtract(FGSDPPageRef page, CGSize size, UInt32 imageIndex);

#if defined(__cplusplus)
}
#endif

#endif// __FGSEPUB__
/** @} */